home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr48 / 386p_200.zip / XSDRV.TXT < prev    next >
Text File  |  1995-01-14  |  12KB  |  232 lines
  1. Format of an XSD driver.
  2. An XSD driver is compiled as a single 32bit segment starting
  3. from offset ZERO and with the "XSD header" first.
  4. The init code will receive the "fixup" offset where the driver is loaded.
  5. Remember that any driver can access the "386Power internal vars"
  6. using the definitions contained into head32.inc
  7.  
  8. When the XSD driver is loaded, 386Mixer has to
  9. "copy & convert to code32 relative offsets"
  10. all the offsets and values from the XSD device header
  11. to the "device table" (see XSD.TXT).
  12.  
  13. Then it has to load the last configuration info
  14. (IRQ,BASE,DMA channel) into the device table.
  15.  
  16. Then it has to "set" the current environment var value.
  17.  
  18. At last it has to call _XSDInit to let the driver select the proper configuration.
  19.  
  20. Then 386mixer has to check if _XSD_IRQ == 0 (timer driven sound system)
  21. and if this is true IT MUST HANDLE DIRECTLY the timer
  22. (using the 386timer module).
  23.  
  24. So the "playback rate" has to be controlled directly by 386mixer by programming
  25. the timer.
  26. With "timer sound", the "sound interrupt" is actually a timer routine
  27. (_XSDTimed) called when the time count elapses.
  28.  
  29. When _XSD_IRQ == 0 it is up to 386mixer to set up a "timer handler"
  30. and the appropriate timer rate to make sound (calling _XSDTimed
  31. when the timer interval elapses).
  32. If _XSD_IRQ is different from zero, it means it is up to _XSD_ON
  33. to set up an irq handler and "program" the appropriate playback rate.
  34.  
  35. The reverse applies to _XSD_OFF (if _XSD_IRQ == 0 , it just has to
  36. "turn off" output, it will be up to the 386mixer to deinstall
  37. the timer handler).
  38.  
  39. Offsets of "device entries" starting from the beginning of the driver data:
  40. __XSDSignature=0     there must be four bytes as follows:
  41.                      db 'XSD',0
  42.                      This means XSD revision ZERO
  43. __XSDInit=4          ; driver-base relative pointer to the
  44.                      ; "hardware check" and system initialization code
  45.                      ; it will also initialize all data structures needed
  46.                      ; by the driver.
  47.                      ; IN: ebp=driver base offset (code32 relative)
  48.                      ;         (use this to fix-up addresses)
  49.                      ;     edi=XSD device table
  50.                      ;         (code 32 relative offset
  51.                      ;          of _XSDTable, from it you know
  52.                      ;          where the other "XSD variables" are
  53.                      ;          and where the sound channel descriptors are)
  54.                      ; OUT:
  55.                      ;     If carry clear then OK
  56.                      ;     else
  57.                      ;         EAX=error code
  58.                      ;                  0 = device not recognized
  59.                      ;                  1 = not enough memory
  60.                      ;                  2 = XSD device table contains
  61.                      ;                      wrong values
  62.                      ; N.B.
  63.                      ; Before calling this, the 386mixer module
  64.                      ; has to read the environment var
  65.                      ; with name pointed by _XSDEnvVar
  66.                      ; copy and convert it to code32 relative offset
  67.                      ; (the pointer name) into the XSD device table
  68.                      ; and then set the pointer to the "environment value"
  69.                      ; string.
  70.  
  71.  
  72. __XSDSetup=8         ; driver-base relative pointer to the
  73.                      ; sound system setup routine
  74.                      ; Simply set properly the values into the
  75.                      ; XSD device table (playback frequency, feed frequency
  76.                      ; active channels, types of emulation
  77.                      ; etc.etc.)
  78.                      ; and then call this.
  79.                      ; IN: none
  80.                      : OUT: XSD table set to the NEAREST supported values.
  81.                      ;      all channels "preset" to silence.
  82.  
  83. __XSDON=12           ; driver-base relative pointer to routine that
  84.                      ; turns on sound system (setting up IRQ handlers
  85.                      ; locking DMA channels, starting up transferts
  86.                      ; AND turning ON sound output).
  87.                      ; THIS ROUTINE will at least "set up" an IRQ handler
  88.                      ; to handle "end of DMA" from soundcard
  89.                      ; and calls to the _SOFTCHANNELIZER
  90.                      ; "mixer emulation" routine.
  91.  
  92. __XSDOFF=16          ; driver-base relative pointer to routine that
  93.                      ; turns off sound system (turns off sound output
  94.                      ; disables DMA, unlocks DMA channel, restore IRQ handlers)
  95.  
  96. ; the following entries may be not supported, it will be up to
  97. ; __XSDInit to set correctly the flags into _XSD_DRVTYPE (into XSD device table)
  98. ; to tell 386mixer what is supported and what's not
  99.  
  100. __XSDMVol=20         ; driver-base relative pointer to
  101.                      ; MASTER VOLUME CONTROL routine
  102.                      ; this affects the output volume of all active channels
  103.                      ;
  104.                      ; actual_channel_volume = (chan_volume/255)*master_volume
  105.                      ;
  106.                      ; IN: al=channel volume (0..255)
  107.                      ;        0   = sound off
  108.                      ;        255 = maximum output
  109.                      ;
  110.                      ; The master volume can have a coarser granularity
  111.                      ; than sound channel volume
  112.                      ; (i.e. on a sound blaster Pro, master volume can range
  113.                      ;       between 0..15 if you just use "output volume"
  114.                      ;       but if you split master volume with
  115.                      ;       the lower four bits controlling
  116.                      ;                          "voice volume" (0..15)
  117.                      ;       and the higher four bits controlling
  118.                      ;                          "output volume" (0..15)
  119.                      ;       you can get the "complete" 0..255 range.
  120.  
  121. ; these entries are specific of "wavetable" soundcards
  122. ; (flag xsd_wavedriver set)
  123.  
  124. __XSDPlay=24         ; driver-base relative pointer to routine that
  125.                      ; plays a sound sample
  126.                      ; IN: esi= ptr to the sound channel descriptor
  127.                      ;          describing what to play and HOW to play it
  128.  
  129. __XSDVol=28          ; driver-base relative pointer to routine that
  130.                      ; sets volume level/ramp only
  131.                      ; IN: esi= ptr to the sound channel descriptor
  132.                      ;          describing what to play and HOW to play it
  133.  
  134. __XSDPan=32          ; driver-base relative pointer to routine that
  135.                      ; sets panning level/ramp only
  136.                      ; IN: esi= ptr to the sound channel descriptor
  137.                      ;          describing what to play and HOW to play it
  138.  
  139. __XSDRate=36         ; driver-base relative pointer to routine that
  140.                      ; sets playback rate ratio (relative to playback freq)
  141.                      ; level/ramp only
  142.                      ; IN: esi= ptr to the sound channel descriptor
  143.                      ;          describing what to play and HOW to play it
  144.  
  145. __XSDEnvVar=40       ; driver-base relative pointer to ASCIIZ string
  146.                      ; with the name of the MS-DOS ENVIROMENT VAR
  147.                      ; to check for config info
  148.                      ;(for a sound blaster it is "BLASTER",0 )
  149.  
  150. __XSDMenu=44         ; driver-base relative pointer to
  151.                      ; User driven "driver setup" menu for custom configuration
  152.                      ; ("executing" this menu results in interactive calls to
  153.                      ;   __XSDSetup subroutines)
  154.  
  155. __XSDCardType=48     ; driver-base relative pointer to ASCIIZ string
  156.                      ; max. 30 character long
  157.                      ; (use this in the "choose driver" list)
  158.  
  159. __XSDProgrammer=52   ; driver-base relative pointer to ASCIIZ string
  160.                      ; with multiple lines of text,max. 40 char each
  161.                      ; (use the LF char (code 10h) to mark newlines)
  162.                      ; (extended info on driver)
  163.  
  164. __XSDNotes=56        ; driver-base relative pointer to ASCIIZ string
  165.                      ; with multiple lines of text,max. 40 char each
  166.                      ; (use the LF char (code 10h) to mark newlines)
  167.                      ; of notes about the driver usage and supperted display
  168.                      ; cards.  (detailed info)
  169. __XSDWClear=60       ; driver-base relative pointer to routine that
  170.                      ; "resets" wavetable ram to "all free"
  171. __XSDWMark=64        ; driver-base relative pointer to routine that
  172.                      ; "marks" currently used wavetable ram
  173.                      ; OUT: eax= mark handle
  174. __XSDWRelease=68     ; driver-base relative pointer to routine that
  175.                      ; releases wavetable ram from the higher "currently in use"
  176.                      ; location down to the "marked" position
  177.                      ; IN: eax= mark handle that will be the new
  178.                      ;          "currently in use" limit
  179. __XSDWUpLoad=72      ; driver-base relative pointer to routine that
  180.                      ; "loads" into wavetable ram a sound sample
  181.                      ; and returns info about it in "soundcard specific"
  182.                      ; units.
  183.                      ; IN: eax= sample size in dwords
  184.                      ;     edx= sample data ptr
  185.                      ; OUT:
  186.                      ;   IF carry clear THEN
  187.                      ;      eax= "internal" sample size count
  188.                      ;      edx= "internal" sample data ptr
  189.                      ;   ELSE
  190.                      ;       carry set, not enough wavetable ram
  191.                      ;   END-IF
  192.  
  193. __XSDTimed=76        ; driver-base relative pointer to routine
  194.                      ; called by 386timer to "emulate a sound irq"
  195.                      ; for sound hardware without irq support
  196.                      ; (i.e. the pc-speaker)
  197.                      ; such drivers set _XSD_IRQ to zero
  198.                      ; to tell the mixer it MUST call _XSDTimed
  199.                      ; to produce sound.
  200.  
  201. Appendix: Some further explanations about the XSD interface:
  202.  
  203. Into XGE you will never see XSD if you don't want to, the only thing you have
  204. to do is select the driver, the initialization code will load it
  205. and let it self-initialize, is you want to make a cool setup program
  206. you can include a "self configure" option
  207. (by checking the environment value or going diectly to hardware or bios)
  208. but ALWAYS include a "user driven configuration" option.
  209.  
  210. If everything else fails, try to call me on the following internet addresses
  211.  knight@maya.dei.unipd.it
  212. but keep in mind that for most of 1995 i will be in the army
  213. (mandatory militar service here in Italy) so i won't access frequently
  214. (AND IT MAY ALSO EXPIRE!!!)
  215. my internet account on the Engineering Department at Padova.
  216.  
  217. My plain mail address is at the end of tech.txt.
  218.  
  219. Ciao,
  220.    Lorenzo Micheletto   knight@maya.dei.unipd.it
  221.                         
  222. N.B. If you want to extend the capabilities of the XVD drivers
  223.      (new functions, etc, etc) set up a portable interface
  224.      (not a thing good for your graphic card only)
  225.      and call it 'XSD1' and so on, but before doing this look into
  226.      x2ftp.oulu.fi to see if someone else did it before you, check if the
  227.      already published release is good enough, if not, publish yours
  228.      with a successive number (i.e. XSD2, XSD3, etc. etc.).
  229.  
  230.  
  231.  
  232.